'\" t
.\"     Title: gldb-gui
.\"    Author: 
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\"      Date: July 2010
.\"    Manual: Bugle user manual
.\"    Source: BUGLE 0.0.20150628
.\"  Language: English
.\"
.TH "GLDB\-GUI" "1" "July 2010" "BUGLE 0.0.20150628" "Bugle user manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
gldb-gui \- graphical OpenGL debugger
.SH "SYNOPSIS"
.HP \w'\fBgldb\-gui\fR\ 'u
\fBgldb\-gui\fR \fIyour\-program\fR [\fIargument\fR...]
.SH "GETTING STARTED"
.PP
The command above will start
\fBgldb\-gui\fR, but will not start your program\&. To do that, use
Run → Run\&. Your program will automatically stop if it generates an OpenGL error\&. You can also stop it manually by selecting
Run → Stop (Ctrl+Break)\&. See
the section called \(lqSETTING BREAKPOINTS\(rq
for information on stopping your program when it calls particular OpenGL functions\&. You can continue your program with
Run → Continue (Ctrl+F9), continue until the next OpenGL function call with
Run → Step (F8), or kill it with
Run → Kill (Ctrl+F2)\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBTip\fR
.ps -1
.br
.PP
Your program can only be stopped or killed when it calls an OpenGL function\&. If your program updates its display only when necessary, it may not stop immediately\&. You can often force it an update by placing another window over your program and then removing it again\&.
.sp .5v
.RE
.PP
The interface is separated into a number of tabs\&. You can browse them at any time, but the information will only be up\-to\-date when your program is stopped\&. When your program is running, the status bar will contain the text
Running\&.
.SH "EXAMINING OPENGL STATE"
.PP
The initial tab is the
State
tab\&. It shows all OpenGL state that is textual rather than an image\&. The state is organised more or less according to the state tables in the
\m[blue]\fBOpenGL specification\&.\fR\m[]\&\s-2\u[1]\d\s+2
OpenGL has an overwhelming amount of state, so some tools are provided to make it easier to find answers:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
To find a specific state, press
Ctrl+F\&. This opens a text entry box where you can type in the name of the state\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
To show only the states that changed since the last time the program was stopped, check the
Show only modified
checkbox\&. These states are also shown in bold\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
To track only a small set of states, check the checkboxes next to those states, then check the
Show only selected
checkbox\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
To save all the states to an XML file, click the
Save
button\&.
.RE
.SS "Examining buffers"
.PP
The
Buffers
tab shows OpenGL buffers (vertex buffer objects)\&. The
Buffer
combobox allows a buffer to be selected\&. By default, the buffer is decoded as a sequence of unsigned bytes, but a format specification can be filled in below the combobox to control the decoding\&. It works best when the entire buffer contains repetitions of a single structure format\&.
.PP
Suppose that the buffer contains a sequence of vertices, each consisting of a 3 GLfloats for the position, 3 unsigned bytes for a colour, and a byte of padding to make the stride 16 bytes\&. Then fill in the format field with
\fBfffbbb_\fR
or more compactly,
\fB3f3b_\fR\&. A description of the available letters for specifying types appears below the entry box\&.
.SS "Examining textures"
.PP
The
Textures
tab shows OpenGL textures\&. The
Texture
combobox allows a texture to be selected, with the currently bound texture of each type shown in bold\&. For cubemap textures, the
Face
combobox allows one of the sides to be examined in detail; the default is to show two views of the cube itself\&. For 3D textures, a slice may be selected with the
Z
combobox\&.
.PP
The apparent size of the texture is controlled through the
Zoom
combobox\&.
Fit
makes the texture as large as possible while still fitting the window\&. The other settings set a ratio between texels and screen pixels\&. The toolbar also has buttons to
[IMAGE]<objectinfo>GTK+</objectinfo>\&\s-2\u[2]\d\s+2 []
zoom in,
[IMAGE]<objectinfo>GTK+</objectinfo>\&\s-2\u[3]\d\s+2 []
zoom out, set a
[IMAGE]<objectinfo>GTK+</objectinfo>\&\s-2\u[4]\d\s+2 []
1:1 ratio, or
[IMAGE]<objectinfo>GTK+</objectinfo>\&\s-2\u[5]\d\s+2 []
fit to the window size\&.
.PP
The appearance of the texture may be controlled with the
Mag filter
and
Min filter
comboboxes\&. These settings correspond to the
GL_TEXTURE_MAG_FILTER
and
GL_TEXTURE_MIN_FILTER
in OpenGL\&. However, these settings are only used for displaying the texture, and do not affect your program\&. The
Level
combobox makes it possible to examine specific texture levels\&. The default (Auto) uses mipmapping as defined by
Min filter\&.
.PP
In some cases, there may not be enough contrast in the texture to see any details (this is particularly true of textures that encode non\-graphical information, such as lookup tables)\&. Checking
Remap range
will scale the colour range up (or down) to cover the whole [0, 1] range\&. To perform more detailed image analysis, use the
[IMAGE]<objectinfo>GTK+</objectinfo>\&\s-2\u[6]\d\s+2 [Copy]
button to copy the texture to the clipboard, and paste it into an external application such as the GIMP\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
The copy feature is only available when compiled with GTK+ 2\&.6 or later\&.
.sp .5v
.RE
.SS "Examining framebuffers"
.PP
Framebuffers may be viewed in much the same way as textures (see
the section called \(lqExamining textures\(rq)\&. The
Framebuffer
may be set to either the current window\-system framebuffer, or to a framebuffer created with
\fBglCreateFramebufferEXT\fR\&. Pbuffers that are no the current drawable are not supported\&.
.PP
Within a framebuffer,
Buffer
may be set to the front buffer, back buffer, depth buffer, stencil buffer or an auxiliary buffer, depending on which buffers actually exist\&.
.SS "Examining shaders"
.PP
The
Shaders
tab shows the source of low\-level ARB shaders and high\-level GLSL shaders\&. Vendor\-specific shader extensions are not supported\&. The current shader of each type is shown in bold in the combobox\&.
.PP
Further information about the shader may be found on the
State
tab\&.
.SH "SETTING BREAKPOINTS"
.PP
The
Breakpoints
allows breakpoints to be set on specific OpenGL functions\&. Immediately before calling the function, your program will be stopped and the status bar will indicate which function caused the breakpoint\&.
.PP
Click
Add
to set a new breakpoint, and enter the name of the function into the dialog box that appears\&. To remove a function from the list, click
Remove\&. If you are likely to want to break on that function later, it is easier to deselect the
Enabled
checkbox for the function, and select it again later\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBTip\fR
.ps -1
.br
.PP
Keep in mind that a function may have multiple aliases (for example,
\fBglBeginQuery\fR
and
\fBglBeginQueryARB\fR), and you need to select the right one\&.
.sp .5v
.RE
.PP
By default,
\fBgldb\-gui\fR
will stop when a function generates an OpenGL error\&. This can be disabled by deselecting
Break on errors\&. Note that function breakpoints occur before the function is called, but errors occur afterwards, so
\fBgldb\-gui\fR
may stop twice for the same function\&.
.SH "INTERACTING WITH GDB"
.PP
When your program is stopped, the
Backtrace
tab shows the current call stack of your program, as
\fBgdb\fR
would\&. The first few frames (usually those up to
\fBrun_filters\fR) will be internal to
bugle\&.
.PP
To further examine the state of your program, select
Run → Attach GDB\&. Provided that you have
\fBxterm\fR
and
\fBgdb\fR
installed, this will open a terminal window running
\fBgdb\fR, already attached to your program\&. Once you have finished, you may either quit
\fBgdb\fR
and detach it from your program, or keep it open and
\fBcontinue\fR
in
\fBgdb\fR\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
Your program needs to be running from the point of view of
\fBgdb\fR
for
\fBgldb\-gui\fR
to function correctly\&. In particular, this feature does not work for remote debugging\&.
.sp .5v
.RE
.SH "REMOTE DEBUGGING"
.PP
Debugging on a single machine is not always practical, because the target application may run full\-screen, or take over the keyboard or mouse\&.
.PP
Several options exist to use
\fBgldb\-gui\fR
on a separate machine to the target application\&. However,
\fIall\fR
of them require trust between the two machines involved as the debugging protocol is not error\-checked and so it would be easy for either a rogue target to attack
\fBgldb\-gui\fR
or vice versa\&.
.PP
Regardless of the method used, the GL implementation running the debugger must in some respects be at least as capable as the display running the target application\&. Specifically, any texture that you view is loaded into an equivalent texture in the debugger, and so the texture target and dimensions must be supported there\&. Note that even if
bugle
was built for OpenGL ES, the debugger will use OpenGL\&.
.SS "Remote X11, target on local display"
.PP
The easiest and most robust option is to rely on the networking in the X Windowing System\&. From the machine containing the target, start
\fBgldb\-gui\fR
with a suitable
\fBDISPLAY\fR
to place the GUI on a remote machine\&. Then go to
Options → Target
and set the display to the local machine (usually :0\&.0)\&.
.PP
Although X11 can directly connect to a remote display over the network, this is not an encrypted connection and may not be secure\&. SSH has an X\-forwarding option (\fB\-x\fR), but with the default setting it does not forward GLX and so it will not work if you have compiled gldb\-gui with OpenGL support\&. However, the
\fB\-Y\fR
forwards the connection as
trusted, and in this mode GLX is supported\&. Please see
\fBsecurity\fR(7)
to understand the security implications of this before you proceed\&.
.SS "Remote X11, target on remote display"
.PP
The same setup as above may be used in reverse: the target runs on a remote display, while
\fBgldb\-gui\fR
runs on the local display\&. The disadvantage of this is that the application is now using indirect rendering, which may affect its performance as well as its behaviour\&.
.SS "SSH\-tunnelled debugger protocol"
.PP
This scenario is experimental and fragile\&. The debugger and target execute on separate machines, and communicate over SSH rather than through a local pipe\&. Because the debugger protocol was not designed for networking, this currently places severe restrictions on the machines used:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
They must use the same byte representations for types\&. In particular, they must have the same endianness, and it may be necessary for them to have the same word size\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Any types used on the target must also be known to the debugger\&. Ideally, one should use the same version of
bugle, compiled with the same compiler and the same OpenGL headers\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The
Backtrace
tab and the
Attach GDB
action will not work\&.
.RE
.PP
To use this mode, go to
Options → Target
and change the mode to
Remote via SSH\&. In the remote host, put the hostname as it will be passed to
\fBssh\fR(1)
(it can also contain a username)\&. You must also configure
ssh
to log into the machine without prompting for a password\&.
.SS "TCP/IP connection"
.PP
This is similar to the SSH option, but does not require SSH to be available, making it suitable for embedded systems with OpenGL ES\&. First, start the application on the target, with the following environment variables:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\fBLD_PRELOAD\fR\fR\fB=libbugle\&.so\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\fBBUGLE_DEBUGGER\fR\fR\fB=tcp\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\fBBUGLE_DEBUGGER_PORT\fR\fR\fB=\fR\fB\fIport\fR\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\fBBUGLE_DEBUGGER_HOST\fR\fR\fB=\fR\fB\fIhost\fR\fR
(optional)
.RE
.PP
This will open a listener on
\fIport\fR\&. By default, it will listen on all interfaces, but can be made to bind to a specific interface by setting
\fBBUGLE_DEBUGGER_HOST\fR\&.
.PP
Once the target has been started, go to
Options → Target
and change the mode to
Remote via TCP/IP\&. You will then be able to fill in the host and port of the target\&. Once this setup is done, select
Run → Run
to start the debugging session\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBWarning\fR
.ps -1
.br
.PP
This mode does not use any kind of authentication or encryption, so should only be used on a trusted network\&.
.sp .5v
.RE
.SH "AUTHOR"
.PP
bugle
is written and maintained by
Bruce Merry\&.
.SH "SEE ALSO"
.PP
\fBbugle\fR(3),
\fBssh\fR(1),
\fBsecurity\fR(7)
.SH "NOTES"
.IP " 1." 4
OpenGL specification.
.RS 4
\%http://www.opengl.org/registry/doc/glspec21.20061201.pdf
.RE
.IP " 2." 4
[set $man.base.url.for.relative.links]/gtk-zoom-in.png
.IP " 3." 4
[set $man.base.url.for.relative.links]/gtk-zoom-out.png
.IP " 4." 4
[set $man.base.url.for.relative.links]/gtk-zoom-100.png
.IP " 5." 4
[set $man.base.url.for.relative.links]/gtk-zoom-fit.png
.IP " 6." 4
[set $man.base.url.for.relative.links]/gtk-copy.png
